<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="umsroot.css">
<TITLE>
Document Generation Tools
</TITLE>
</HEAD>
<BODY >
<A HREF="umsroot085.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot083.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot087.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc208">15.3</A>&nbsp;&nbsp;Document Generation Tools</H2>

The document generation tools library provides a set of predicates for 
the generation of documentation from ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> program sources. The 
tools generate documentation by processing the
<A HREF="../bips/kernel/directives/comment-2.html"><B>comment/2</B></A><A NAME="@default872"></A>
directives in each source file. The following is an example comment for 
the <B>n-queens</B> example:
<BLOCKQUOTE CLASS="quote">
<PRE CLASS="verbatim">
% comment for queen/2
:- comment(queen/2, [
 
    summary: "Program that solves the attacking Queens problem for
              an arbitrary number of queens.",
 
    index: ["NQueens Problem"],
 
    args: ["Data": "List modelling initial state of queens on board.",
       "Args": "Solution list of Y-coordinate of each queen on the 
        board."],
 
    amode: queen(+,-),
    amode: queen(-,+),
    amode: queen(+,+),
 
    resat: yes,
 
    fail_if: "A solution cannot be found where all queens are safe
              from attack by every other.",
 
    see_also:
        [queens8/1, queensN/1],
 
    desc: html("The problem is to arrange a specified number of queens
           on a chessboard such that no queen attacks any other queen
           The predicate takes a list representing the initial state
           of the queens on the board, with each element representing
           a queen and its current Y-coordinate. If a solution is 
           found, a list is returned specifying the safe Y-coordinate 
    for each queen.")
   ]).  % end of comment directive for queen/2
</PRE></BLOCKQUOTE>
There are two pertinent predicates for document generation. The first, 
<A HREF="../bips/lib/document/icompile-2.html"><B>icompile/2</B></A><A NAME="@default873"></A> generates an 
information file (.eci) by extracting information from a source file (.ecl).
The second,
<A HREF="../bips/lib/document/eci_to_html-3.html"><B>eci_to_html/3</B></A><A NAME="@default874"></A>, 
processes this information file to produce readable HTML and plain text files.
By default, these files are placed in a subdirectory with the 
same name as the information file, but without the extension. 
The generated files are <TT>index.html</TT>, containing a summary 
description of the library, plus one HTML and one plain text file 
for each predicate that was commented using a comment/2 directive 
in the source.<BR>
<BR>
The following produces the <TT>queen.eci</TT> file and a <TT>queen</TT>
directory in the current directory. Within the queen directory reside
<TT>index.html</TT>, <TT>queen-2.html</TT> and <TT>queen-2.txt</TT>:
<BLOCKQUOTE CLASS="quote">
<PRE CLASS="verbatim">
?- lib(document).
document.ecl compiled traceable 83620 bytes in 0.04 seconds
Yes (0.04s cpu)

?- icompile(queen, ".").
queen.ecl  compiled traceable 1432 bytes in 0.01 seconds
/examples/queen.eci generated in 0.00 seconds.
Yes (0.01s cpu)

?- eci_to_html(queen, ".", "").
Yes (0.00s cpu)
</PRE></BLOCKQUOTE>
<HR>
<A HREF="umsroot085.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot083.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot087.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
